Skip to content

fix: add boolean string coercion for FastMCP tool parameters#1848

Closed
jayhemnani9910 wants to merge 1 commit intomodelcontextprotocol:mainfrom
jayhemnani9910:fix/1843-bool-string-coercion
Closed

fix: add boolean string coercion for FastMCP tool parameters#1848
jayhemnani9910 wants to merge 1 commit intomodelcontextprotocol:mainfrom
jayhemnani9910:fix/1843-bool-string-coercion

Conversation

@jayhemnani9910
Copy link

@jayhemnani9910 jayhemnani9910 commented Jan 12, 2026

Summary

Some LLM clients incorrectly serialize booleans as strings ("false" instead of false in JSON). This causes FastMCP tools to receive
the string 'false' instead of Python False, making if param: checks evaluate incorrectly.

Root Cause

The existing pre_parse_json method was supposed to handle this via json.loads, but boolean values were being skipped because:

  1. json.loads("false") correctly returns Python False
  2. However, bool is a subclass of int in Python
  3. The skip condition isinstance(pre_parsed, str | int | float) matches booleans (since isinstance(False, int) is True)
  4. So the parsed boolean was discarded

Changes

  • Added explicit case-insensitive boolean string coercion in pre_parse_json method
  • Handles "true"/"false" strings (any case) → Python True/False
  • Processing happens before the generic JSON parsing logic
  • Only applies when parameter annotation is bool

Testing

  • Added 6 comprehensive test cases
  • All 39 func_metadata tests pass
  • All 329 FastMCP tests pass
  • Linter (ruff) passes
  • Type checker (pyright) passes

Related Issues

Fixes #1843

fix: add boolean string coercion for FastMCP tool parameters
674d7b4 
Some LLM clients incorrectly serialize booleans as strings ("false"
instead of false in JSON). The existing pre_parse_json method was
supposed to handle this via json.loads, but boolean values were being
skipped because bool is a subclass of int in Python, and the skip
condition isinstance(pre_parsed, str | int | float) matches booleans.

This fix adds explicit case-insensitive boolean string coercion before
the generic JSON parsing logic, properly converting "true"/"false"
strings to Python True/False when the parameter annotation is bool.

Fixes modelcontextprotocol#1843
Copilot AI review requested due to automatic review settings January 12, 2026 04:59
Copilot AI reviewed Jan 12, 2026
View reviewed changes
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR fixes an issue where LLM clients incorrectly serialize boolean values as strings (e.g., "false" instead of false in JSON), causing FastMCP tools to receive string values instead of Python booleans. This made if param: checks evaluate incorrectly since the string 'false' is truthy in Python.

Changes:

  • Added explicit case-insensitive boolean string coercion in the pre_parse_json method to convert "true"/"false" strings to Python True/False
  • Added 6 comprehensive test cases covering lowercase, case-insensitive, native booleans, non-boolean strings, runtime validation, and type-specific behavior
  • The fix is applied before generic JSON parsing to handle the edge case where json.loads("false") returns False, but isinstance(False, int) is True, causing the parsed boolean to be skipped

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File Description
src/mcp/server/fastmcp/utilities/func_metadata.py Added boolean string coercion logic in pre_parse_json method to handle string "true"/"false" values for bool-annotated parameters
tests/server/fastmcp/test_func_metadata.py Added 6 comprehensive test functions validating boolean coercion for various cases including case-insensitivity, native booleans, non-boolean strings, runtime validation, and type specificity

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@Kludex
Copy link
Member

Kludex commented Jan 15, 2026

Can I have a very simple MRE to understand what is wrong?

@jayhemnani9910
Copy link
Author

jayhemnani9910 commented Jan 16, 2026 •
edited by Kludex
Loading

Can I have a very simple MRE to understand what is wrong?

I might be wrong🙃, please let me know accordingly.

from mcp.server.fastmcp.utilities.func_metadata import FuncMetadata

def my_tool(enabled: bool) -> str:
    if enabled:
        return "enabled"
    return "disabled"

metadata = FuncMetadata.from_callable(my_tool)

# LLM client sends "false" as a string instead of JSON false
args = metadata.pre_parse_json({"enabled": "false"})

# Before fix: args = {"enabled": "false"} → if "false": is True ❌
# After fix:  args = {"enabled": False}  → if False: is False ✓

Why it broke:

  1. json.loads("false") correctly returns Python False

  2. But isinstance(False, int) is True (bool is a subclass of int)

  3. So the skip condition isinstance(pre_parsed, str | int | float) matched

  4. The parsed boolean was discarded, keeping the original string "false"

@Kludex
Copy link
Member

Kludex commented Jan 16, 2026

You aren't supposed to call pre_parse_json. Can you show me an example of a real minimal FastMCP application that has an issue? Please wrap the code in "```".

@maxisbey
Copy link
Contributor

maxisbey commented Feb 10, 2026

Thanks for the PR! We're still discussing whether this coercion should live in the SDK — see #1843. Going to close this for now and defer the decision to the issue.

AI Disclaimer

@maxisbey maxisbey closed this Feb 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Function parameter coercion ("false" => False) failures in properly documented FastMCP tools?

3 participants

@jayhemnani9910 @Kludex @maxisbey